home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr47 / 335_04.zip / BASE.TXT < prev    next >
Text File  |  1993-04-13  |  50KB  |  1,519 lines

  1.  
  2.  
  3.  
  4.                   Frankenstein Cross Assemblers Users Manual
  5.  
  6.                                  Mark Zenier
  7.  
  8.  
  9.  
  10.  
  11.           1.  Disclaimer
  12.  
  13.           This software is in the public domain.  Any prior
  14.           copyright claims are relinquished.
  15.  
  16.           This software is distributed with no warranty whatever.
  17.           The author takes no responsibility for the consequences of
  18.           its use.
  19.  
  20.  
  21.           2.  Introduction
  22.  
  23.           2.1  This_Manual
  24.  
  25.           This manual covers the basic features for the Frankenstein
  26.           cross assemblers.  The specific features for a given
  27.           target architecture will be covered in the appendix for
  28.           that cross-assembler.
  29.  
  30.           2.2  Notation
  31.  
  32.           Items enclosed in [] are optional. The "[]" are not
  33.           entered in the source statement or command line, and are
  34.           just a notation.
  35.  
  36.  
  37.           3.  Invocation
  38.  
  39.           name [-o binary] [-l listing] [-s symbols] [-d] input
  40.  
  41.           The optional operands on the command line can be in any
  42.           order.
  43.  
  44.           3.1  Input_File
  45.  
  46.           The input file must appear after the optional entries on
  47.           the command line.  Only one input file is used with this
  48.           version. If the file name is a single minus sign, the
  49.           standard input is used.
  50.  
  51.           3.2  Listing_File
  52.  
  53.                -l filename
  54.  
  55.           An annotated listing will only be produced if an optional
  56.           list file is provided, otherwise the error messages and
  57.           summary will be output to the console.  There is no
  58.           required suffix or default extension for the file name.
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                     - 2 -
  71.  
  72.  
  73.  
  74.           3.3  Hex_Output_File
  75.  
  76.                -h filename or
  77.                -o filename
  78.  
  79.           The binary output will only be produced if the optional
  80.           file is provided.  See the section in the description of
  81.           the output files for the format of the data records.  If
  82.           any errors occur, the hex output file is either not
  83.           created or is deleted depending on whether the error
  84.           occurred in the input or output phases of processing.
  85.           There is no required suffix or default extension for the
  86.           file name.
  87.  
  88.           3.4  Symbol_Listing_File
  89.  
  90.                -s filename
  91.  
  92.           The symbol table is dumped with one entry per line for
  93.           whatever use is desired, normally with the sort utility to
  94.           produce symbol listings in a different order that the one
  95.           provided.  See the section on the output files for a
  96.           description of the format.  There is no required suffix or
  97.           default extension for the file name.
  98.  
  99.           3.5  Debug
  100.  
  101.           The -d debug option
  102.  
  103.              - Saves the intermediate file in the /usr/tmp directory
  104.  
  105.              - Calls the abort() system call to produce a "core"
  106.                file
  107.  
  108.           3.6  Processor_Selection
  109.  
  110.                assembler name or
  111.                -p string
  112.  
  113.           Some of these assemblers support related families of
  114.           processors, and can be limited to specific subsets of the
  115.           total instructions by sending the processor number or name
  116.           as an operand.  The operand is scanned for unique
  117.           substrings which identify the target processor.  The
  118.           operand can be either the name of the executable, or the
  119.           operand of the -p option, with the operand of the -p
  120.           having precedence.  The name of the executable may not
  121.           available in some operating systems.  The CPU pseudo-
  122.           operation has precedence over both the name scan and the
  123.           -p operand [see the appendix for the specific processor].
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                     - 3 -
  137.  
  138.  
  139.  
  140.                Example
  141.  
  142.                a6800 for the mc6800 instruction set
  143.                a6801 for the 6801/6803 instruction set
  144.                a6811 for the mc68hc11 instruction set
  145.  
  146.  
  147.           4.  Source_Input_File
  148.  
  149.           The source input is a text file a with one statement per
  150.           line.  Adjacent symbols must be separated by spaces or
  151.           tabs or special characters such as operators or
  152.           parenthesis.
  153.  
  154.           4.1  Input_Lines
  155.  
  156.           Source lines consist of up to four parts
  157.  
  158.                [Label] [Opcode [Operands] ] [; comments]
  159.  
  160.           Labels    A symbol that starts in the first column of the
  161.                     line is a label. A label is used as the defining
  162.                     instance of a symbol, the place where it is
  163.                     given a value, normally the address of the
  164.                     location in memory where the data generated by
  165.                     the rest of the statement is placed.  Labels are
  166.                     optional for target machine instructions
  167.                     statements.  Label are required on some pseudo-
  168.                     operations, and are not allowed on others.
  169.  
  170.           Opcode    The first symbol in a line that doesn't start in
  171.                     column 1 is treated as an opcode, all symbols
  172.                     after that are treated as symbol references.
  173.                     Opcodes are treated as a separate set of
  174.                     symbols, so a label can have the same character
  175.                     string as an opcode. Opcodes are converted to
  176.                     uppercase for comparison, so case is not
  177.                     significant.
  178.  
  179.           Operands  The rest of the line is the operands associated
  180.                     with the opcode.  These are expressions, symbol
  181.                     references, or other syntactic elements
  182.                     determined by the specific operation.
  183.  
  184.           Comments  Comments start with a ';', anything on a line
  185.                     after a semicolon is ignored.  Lines that
  186.                     consist of only a comment are treated as empty
  187.                     lines.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                                     - 4 -
  203.  
  204.  
  205.  
  206.                Example
  207.  
  208.                ; just a little example
  209.                        org $700
  210.                label   equ *  ; set label to current location
  211.                        adda    #$21 ; a 6800 example
  212.                        end
  213.  
  214.           4.1.1  Limitations  Input lines should be shorter than 256
  215.           characters.  An error message is issued if lines are
  216.           longer.
  217.  
  218.           4.1.2  Empty  Empty lines are ignored as input, but are
  219.           copied to the listing file.
  220.  
  221.           4.2  Syntactic_Elements
  222.  
  223.           4.2.1  Symbols  Symbols are strings of characters.  The
  224.           first of which is one of the following.
  225.  
  226.                A-Z a-z ! & ^ _ ~
  227.  
  228.           The rest of the string consists of zero or more of the
  229.           following.
  230.  
  231.                0-9 A-Z a-z ! & ^ _ ~
  232.  
  233.           There is no length limit to symbols, all characters are
  234.           significant.  Case is significant.
  235.  
  236.           4.2.2  Reserved_Variables_Names  Machine specific names,
  237.           and operator names that can appear in symbolic expressions
  238.           share the same symbol table with labels, and cannot be
  239.           used as labels.  The list will vary from machine to
  240.           machine.  Case is significant for these symbols.
  241.  
  242.                Examples
  243.  
  244.                and defined eq ge gt high le low lt mod ne not or shl
  245.                shr xor AND DEFINED EQ GE GT HIGH LE LOW LT MOD NE
  246.                NOT OR SHL SHR XOR
  247.  
  248.           4.2.3  Numeric_Constants  numeric constants can be
  249.           specified in decimal, hexadecimal, octal, and binary.
  250.           Constants are maintained as long variables, but the
  251.           instruction generation will cause an error if the value is
  252.           too big to fit in its destination field.
  253.  
  254.           4.2.3.1  Decimal_Constants
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                                     - 5 -
  269.  
  270.  
  271.  
  272.              - one or more decimal characters (0-9) followed by an
  273.                optional "d" or "D" base designator.
  274.  
  275.           4.2.3.2  Hexadecimal_Constants
  276.  
  277.                Either
  278.  
  279.              - one or more hexadecimal characters (0-9 a-f A-F)
  280.                preceded by a "$" base designator.
  281.  
  282.              - a decimal character (0-9) followed by zero or more
  283.                hexadecimal characters (0-9 a-f A-F) followed by a
  284.                "h" or "H" base designator
  285.  
  286.           4.2.3.3  Octal_Constants
  287.  
  288.                Either
  289.  
  290.              - one or more octal characters (0-7) preceded by a "@"
  291.                base designator
  292.  
  293.              - one or more octal characters (0-7) followed by a "o"
  294.                or "O" or "q" or "Q" base designator.  Note: this is
  295.                the letter "O" not the number "0".
  296.  
  297.           4.2.3.4  Binary_Constants
  298.  
  299.                Either
  300.  
  301.              - one or more binary characters (0 or 1) preceded by a
  302.                "%" base designator.
  303.  
  304.              - one or more binary characters (0 or 1) followed by a
  305.                "b" or "B" base designator.
  306.  
  307.           4.2.3.5  Examples
  308.  
  309.                123       decimal number
  310.                123d      decimal number
  311.                $faf      hexadecimal number
  312.                0fafh     hexadecimal number, note leading zero used
  313.                          to differentiate this from symbol "fafh"
  314.                @1234     octal number
  315.                1234Q     octal number
  316.                %010101   binary number
  317.                010101b   binary number
  318.  
  319.           4.2.4  String_Constants  String constants are specified
  320.           using either the quotation mark " or the apostrophe '.  A
  321.           string starting with one of these character is terminated
  322.           by only that character and can contain the other string
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                                     - 6 -
  335.  
  336.  
  337.  
  338.           delimiter as data. A string with no characters is valid.
  339.  
  340.           The values generated in the binary output can be different
  341.           from the host computers character set (the default). See
  342.           the section on Defining Target Character Sets.
  343.  
  344.           Within the character string, the backslash is an escape
  345.           character.
  346.  
  347.                \c Character escapes
  348.                               The only characters defined for the
  349.                               default (no) translation are \\ \" \'.
  350.                               Any other translation, (the control
  351.                               characters '\n', '\r', etc.) require a
  352.                               translation table be defined.  Values
  353.                               can be set up for any character
  354.                               following the backslash escape except
  355.                               x and 0 through 7.
  356.  
  357.                \777 Octal character escapes
  358.                               An one, two or three character octal
  359.                               constant.  The one byte value is the
  360.                               binary representation of the number.
  361.                               The value is masked off for a maximum
  362.                               value of 255.
  363.  
  364.                \xFF Hexadecimal character escapes
  365.                               A one or two character hexadecimal
  366.                               constant, preceded by a lower case x.
  367.                               Upper and lower case characters A
  368.                               through F are valid.  The one byte
  369.                               value is the binary representation of
  370.                               the number.
  371.  
  372.                Examples
  373.  
  374.                        "this isn't illegal"
  375.                        'this is the other delimiter'
  376.                        '"'
  377.                        "\xfe\0\n"
  378.  
  379.           4.3  Expressions
  380.  
  381.           Expressions consist of
  382.  
  383.              - Symbolic References
  384.              - Location Counter References
  385.              - Numeric Constants
  386.              - String Constants
  387.              - Operators
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                     - 7 -
  401.  
  402.  
  403.  
  404.           Expressions are used as operands in statements where any
  405.           numeric value or memory address is desired.
  406.  
  407.           4.3.1  Symbols  A symbol reference is the name of an item
  408.           in the symbol table, which has a numeric value associated
  409.           with it.  This value is either the memory address of the
  410.           statement which has this symbol as a label, or the value
  411.           of the expression defined in a SET or EQU statement which
  412.           has this symbol as a label.
  413.  
  414.           4.3.1.1  Forward_References  During the input phase of
  415.           processing, a symbol value may not be known if the
  416.           definition of the symbol has not yet occurred.  Some
  417.           pseudo-operations require that their operand expressions
  418.           have a value at the input phase, so no references to as
  419.           yet undefined symbols can occur in this case.  In the
  420.           output phase of processing, it will result in an error if
  421.           any of the symbols used in expressions do not have values
  422.           defined.
  423.  
  424.           4.3.1.2  Reserved_Symbols_for_Operators  Using reserved
  425.           symbols as labels will result in a syntax error as they
  426.           are predefined as a different type of syntactic element
  427.           than the rest of the symbol table. Operators for which
  428.           there is no special character representation, and items
  429.           like machine register names and condition code types will
  430.           be represented by reserved symbols.  The set of the
  431.           reserved symbols will vary for each target machine, and
  432.           will be documented in the appendix for each target.
  433.  
  434.           4.3.2  Location_Counter  The special name '*' used in an
  435.           expression represents the location of the first byte of
  436.           the binary output for the current statement.  Some
  437.           assemblers use some other character for source code
  438.           compatiblity.
  439.  
  440.           4.3.3  Constants  The form of numeric constants is defined
  441.           in the previous section.
  442.  
  443.           4.3.4  Strings  String constants, as defined in the
  444.           previous section, are valid in expressions.  However, at
  445.           most the first two characters are used.  If the string is
  446.           the null string, i.e. "", the numeric value is zero.  If
  447.           the string is one character long, the value is the value
  448.           of the current character set translation, or the host
  449.           computers character set if no translation is active.  If
  450.           the string is two or more characters long, the value is
  451.           256*(the first character) + (the second character).
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.                                     - 8 -
  467.  
  468.  
  469.  
  470.           4.3.5  Operators
  471.  
  472.           4.3.5.1  Description
  473.  
  474.                '+' expression
  475.                               Unary plus. No real effect.
  476.  
  477.                '-' expression
  478.                               Unary minus, the result is the
  479.                               negative of the expression.
  480.  
  481.                NOT expression
  482.                               Logical negation. The result is 0 if
  483.                               the expression is nonzero, 1 if the
  484.                               expression is 0.
  485.  
  486.                HIGH expression
  487.                               Result is the High half of a two byte
  488.                               number, equivalent to (expression SHR
  489.                               8) AND $FF.
  490.  
  491.                LOW expression
  492.                               Result is the Low order byte of the
  493.                               expression, equivalent to (expression
  494.                               AND $FF)
  495.  
  496.                expression '*' expression
  497.                expression '/' expression
  498.                expression '+' expression
  499.                expression '-' expression
  500.                               Standard arithmetic operations.
  501.  
  502.                expression MOD expression
  503.                               Result is the remainder of the
  504.                               division of the value of the left
  505.                               expression by the right.
  506.  
  507.                expression SHL expression
  508.                expression SHR expression
  509.                               Shift the value of the left expression
  510.                               left or right by the number of bit
  511.                               positions given by the right
  512.                               operation.
  513.  
  514.                expression GT expression
  515.                expression GE expression
  516.                expression LT expression
  517.                expression LE expression
  518.                expression NE expression
  519.                expression EQ expression
  520.                expression '>'  expression
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                                     - 9 -
  533.  
  534.  
  535.  
  536.                expression '>=' expression
  537.                expression '<'  expression
  538.                expression '<=' expression
  539.                expression '='  expression
  540.                expression '<>' expression
  541.                               Relational expressions. If the
  542.                               relation is true, the value is 1. If
  543.                               false, the value is 0.  The operators
  544.                               are nonassociative, the  expression "
  545.                               1 < 3 < 5 " is not legal.
  546.  
  547.                expression AND expression
  548.                expression OR expression
  549.                expression XOR expression
  550.                               Bitwise logical operations.
  551.  
  552.                DEFINED symbol
  553.                               If the symbol (not an expression) is
  554.                               defined, i.e. used as a label, before
  555.                               this point in the input the value is
  556.                               1.  If not, the value is 0.
  557.  
  558.                '(' expression ')'
  559.                               Parenthesis are available to override
  560.                               the operator precedence.
  561.  
  562.           4.3.5.2  Precedence  The precedence of the operators from
  563.           lowest to highest.
  564.  
  565.             1.   HIGH LOW
  566.             2.   OR XOR
  567.             3.   AND
  568.             4.   NOT
  569.             5.   GT GE LE LT NE EQ '>' '>=' '<' '<=' '=' '<>'
  570.             6.   '+' '-'
  571.             7.   '*' '/' MOD SHL SHR
  572.             8.   unary '+' '-'
  573.             9.   ( expression )
  574.  
  575.  
  576.           5.  Statements
  577.  
  578.           The names for the operations and pseudo-operations for
  579.           each assembler are specified in the adaptation files, and
  580.           can be different from the examples given here.
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                                     - 10 -
  599.  
  600.  
  601.  
  602.           5.1  Label_Only_Line
  603.  
  604.           A line with only a label starting in column 1 will define
  605.           that symbol with the current value of the location
  606.           counter.
  607.  
  608.           5.2  End
  609.  
  610.                [Label] END
  611.  
  612.           The End statement terminates the processing of the current
  613.           file.  For an include file, the file is closed and input
  614.           resumes in the file that contained the include statement.
  615.           For the main file, processing shifts to the following
  616.           passes of the assembly.  The end statement is optional, as
  617.           the end of file condition is treated in the same fashion.
  618.           If the optional label is present, The symbol specified is
  619.           used as the execution start address that is output in the
  620.           binary file. The symbol must be used as a label somewhere
  621.           else in the file.  When more than one start address is
  622.           specified, the last one in the file is used.
  623.  
  624.           5.3  File_Inclusion
  625.  
  626.                INCLUDE "filename"
  627.                INCL "filename"
  628.  
  629.           The include statement shifts input from the current file
  630.           to the file specified. Input resumes from the file
  631.           containing the include statement when the end of file or
  632.           the End statement is reached in the included file.
  633.           Includes can be nested up to the limits of the include
  634.           file stack, currently a limit of 20 deep, or the limits of
  635.           the operating system, whichever comes first.  Includes can
  636.           be recursive, i.e., a file can include itself.  If a file
  637.           cannot be opened, either do to an bad filename or a lack
  638.           of system resources, an error is issued.
  639.  
  640.           5.4  Conditional_Assembly
  641.  
  642.           5.4.1  If
  643.  
  644.                IF expression
  645.  
  646.           The IF statement allows selective assembly.  If the
  647.           expression evaluates to a nonzero value, all statements
  648.           between the IF and the matching ELSE or ENDI are
  649.           assembled.  If the expression evaluates to zero, or the
  650.           expression in noncomputable due to a forward reference,
  651.           all statements between the IF and the matching ELSE or
  652.           ENDI are ignored.
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.                                     - 11 -
  665.  
  666.  
  667.  
  668.           Note: it is safer to use the DEFINED operator when testing
  669.           for the existence of a symbol than to rely on the
  670.           noncomputability of an expression.
  671.  
  672.           IF statements can be nested to a depth determined by a
  673.           configuration constant, currently 32.  No label is allowed
  674.           on an IF statement.
  675.  
  676.           5.4.2  Else
  677.  
  678.                ELSE
  679.  
  680.           The ELSE statement causes all statements between it and
  681.           its corresponding ENDI statement to be treated the
  682.           opposite of the statements between the matching IF and
  683.           this statement.  When the expression on the matching IF is
  684.           nonzero, the statements between the ELSE and ENDI are
  685.           ignored.  If the IF expression failed, the statements
  686.           between the ELSE and the ENDI are assembled.  Labels are
  687.           not allowed on ELSE statements.
  688.  
  689.           5.4.3  End_If
  690.  
  691.                ENDI
  692.  
  693.           The ENDI statement terminates processing of its matching
  694.           IF statement.  Labels are not allowed on ENDI statements.
  695.  
  696.           5.5  Symbolic_Constants
  697.  
  698.           Symbols can be assigned numeric values with the SET and
  699.           EQU statements.  The expressions cannot have forward
  700.           references to as yet undefined symbols.
  701.  
  702.           5.5.1  Equate
  703.  
  704.                Label EQU expression
  705.  
  706.           The EQU statement takes the value of the expression and
  707.           creates a symbol with that value.  Symbols defined in EQU
  708.           statements cannot already exist, or be redefined.
  709.  
  710.           5.5.2  Set
  711.  
  712.                Label SET expr
  713.  
  714.           The SET statement sets the symbol specified in the label
  715.           field with the numeric value of the expression.  The SET
  716.           statement can change the value of a symbol, but only if
  717.           the symbol is originally defined in a previous SET
  718.           statement.
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                                     - 12 -
  731.  
  732.  
  733.  
  734.                Example
  735.  
  736.                counter set 1
  737.                counter set counter+1
  738.                counter set counter+1
  739.  
  740.           5.6  Location_Counter_Value_Setting
  741.  
  742.           The address of the generated binary data can be changed
  743.           with the ORG and reserve statements.
  744.  
  745.           5.6.1  Org
  746.  
  747.                [Label] ORG expression
  748.  
  749.           The location counter is set to the numeric value of
  750.           expression.  It is an error if the expression contains
  751.           references to symbols not yet defined.  The optional label
  752.           is set to the new value of the location counter.
  753.  
  754.           5.6.2  Reserve_Memory
  755.  
  756.                [Label] RMB expression
  757.                [Label] RESERVE expression
  758.  
  759.           The reserve memory statement moves the location counter
  760.           forward by the number of bytes specified in the
  761.           expression.  The label is set to the first location of
  762.           this area.
  763.  
  764.           5.7  Data_Definitions
  765.  
  766.           5.7.1  Define_Byte_Data
  767.  
  768.                [Label]  BYTE  expression [, expression] ...
  769.                [Label]  FCB   expression [, expression] ...
  770.                [Label]  DB  expression [, expression] ...
  771.  
  772.           The define byte statement generates one character of data
  773.           for each expression in the expression list.  There can be
  774.           up to 128 expressions on a line, more than the line length
  775.           will allow.  The optional label is set to the first
  776.           location of this area.
  777.  
  778.           5.7.2  Define_Word_Data
  779.  
  780.                [Label]  WORD  expression [, expression] ...
  781.                [Label]  FDB   expression [, expression] ...
  782.                [Label]  DW  expression [, expression] ...
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                                     - 13 -
  797.  
  798.  
  799.  
  800.           The define word statement generates a two byte integer for
  801.           each expression in the expression list.  There can be up
  802.           to 128 expressions on a line, more than the line length
  803.           will allow.  The byte order of the data is determined by
  804.           the adaptation files for the target processor.  The
  805.           optional label is set to the first location of this area.
  806.  
  807.           5.7.3  Define_String_Data
  808.  
  809.                [Label] STRING string [, string] ...
  810.                [Label] FCC string [, string] ...
  811.  
  812.           The define string statement generates data encoded in the
  813.           current character set translation, one byte per character,
  814.           excluding the delimiter characters.  The optional label is
  815.           set to the first location of this area.
  816.  
  817.           5.8  Defining_Target_Character_Sets
  818.  
  819.           The values generated for String Constants in both the
  820.           Define String Data and in expressions can be specified on
  821.           a character by character basis.  This is to support cross
  822.           assembly where the target system has a different character
  823.           set from the host computer.
  824.  
  825.           5.8.1  Define_Character_Set_Translation
  826.  
  827.           Label CHARSET
  828.  
  829.           The define character set translation statement defines a
  830.           name and creates an internal table for a character set.
  831.           The label symbol is treated like the label on an EQU
  832.           statement.  The value is from an internal counter and has
  833.           little or no meaning outside of using it on a CHARUSE
  834.           statement to specify which translation to use.  There can
  835.           be up to 5 [configurable] character translation sets.  A
  836.           CHARSET statement must precede any CHARDEF statements.
  837.  
  838.           5.8.2  Define_Character_Value
  839.  
  840.                CHARDEF string, expression [, expression ] ...
  841.                CHD string, expression [, expression ] ...
  842.  
  843.           The define character value statement set the translation
  844.           for one or more characters in the table defined by the
  845.           preceding CHARSET statement.  There can be more than one
  846.           character in the string, but the number of expression in
  847.           the value list must match the number of characters.  Octal
  848.           and Hexadecimal escape sequences cannot occur in the
  849.           string.
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                                     - 14 -
  863.  
  864.  
  865.  
  866.           There are two sets in each translation table. The first is
  867.           for the characters, the second for characters escaped with
  868.           the backslash.
  869.  
  870.           Note: the characters '"' and '\"' (and "'" and "\'") each
  871.           have an entry in different halves of the translation
  872.           tables.
  873.  
  874.           5.8.3  Use_Character_Translation
  875.  
  876.                CHARUSE
  877.                CHARUSE expression
  878.  
  879.           The use character translation statement changes the
  880.           translation for the following statements.  The statement
  881.           without an expression turns off the translation, so the
  882.           host character set is used.  The statement with an
  883.           expression (the name given on the CHARSET statement) sets
  884.           the translation to the set defined in the respective
  885.           CHARSET.
  886.  
  887.                Example
  888.  
  889.                ascii   charset
  890.                        chardef " !\"#$%&\'",$20,$21,$22,$23,$24,$25,$26,$27
  891.                        chardef "()*+,-./",$28,$29,$2a,$2b,$2c,$2d,$2e,$2f
  892.                        chardef "01234567",$30,$31,$32,$33,$34,$35,$36,$37
  893.                        chardef "89:;<=>?",$38,$39,$3a,$3b,$3c,$3d,$3e,$3f
  894.                        chardef "@ABCDEFG",$40,$41,$42,$43,$44,$45,$46,$47
  895.                        chardef "HIJKLMNO",$48,$49,$4a,$4b,$4c,$4d,$4e,$4f
  896.                        chardef "PQRSTUVW",$50,$51,$52,$53,$54,$55,$56,$57
  897.                        chardef "XYZ[\\]^_",$58,$59,$5a,$5b,$5c,$5d,$5e,$5f
  898.                        chardef "`abcdefg",$60,$61,$62,$63,$64,$65,$66,$67
  899.                        chardef "hijklmno",$68,$69,$6a,$6b,$6c,$6d,$6e,$6f
  900.                        chardef "pqrstuvw",$70,$71,$72,$73,$74,$75,$76,$77
  901.                        chardef "xyz{|}~",$78,$79,$7a,$7b,$7c,$7d,$7e
  902.                        chardef '"', $22 ; not the same table entry as '\"'
  903.                        chardef "'", $27 ;
  904.                        chardef "\n\t\v\b\r\f\a", $0a,$09,$0b,$08,$0d,$0c,$07
  905.                        charuse ascii
  906.  
  907.           5.9  Machine_Instructions
  908.  
  909.                [Label] opcode operands?
  910.  
  911.           Machine instructions generate the binary output by
  912.           evaluating the expressions for the operands, and matching
  913.           the opcode with the entry in the instruction generation
  914.           tables.
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                                     - 15 -
  929.  
  930.  
  931.  
  932.           If the instruction has more than one format which is
  933.           selected by the value of the operands, the selection
  934.           criteria must able to be determined at the input phase of
  935.           processing.  For example, in the mc6800 architecture
  936.           direct address mode, any memory variables that are have an
  937.           address between 0 and 255 must be defined before any
  938.           reference to these symbols.
  939.  
  940.           The optional label is set to the first location of the
  941.           generated instruction.
  942.  
  943.  
  944.           6.  Output
  945.  
  946.           6.1  Program_Generated_Messages_and_Errors
  947.  
  948.           6.1.1  Messages
  949.  
  950.                `` ERROR SUMMARY - ERRORS DETECTED {count}''
  951.                ``               -  WARNINGS       {count}''
  952.                     output at the end of the listing and on the
  953.                     console.
  954.  
  955.           6.1.2  System_Errors
  956.  
  957.                ``cannot open hex output {filename}''
  958.                     file cannot be opened for output. The assembly
  959.                     continues as if the -[oh] option was not
  960.                     specified.
  961.  
  962.                ``cannot open input file {filename}''
  963.                     file cannot be opened for reading. Fatal error.
  964.  
  965.                ``cannot open list file {filename}''
  966.                     file cannot be opened for output. The assembly
  967.                     continues as if the -l option was not specified.
  968.  
  969.                ``cannot open symbol file {filename}''
  970.                     file cannot be opened for output. The assembly
  971.                     continues as if the -s option was not specified.
  972.  
  973.                ``cannot open temp file {filename}''
  974.                     file cannot be opened for input or output. Fatal
  975.                     error.
  976.  
  977.                ``no input file''
  978.                     no input operand specified. Fatal error.
  979.  
  980.                ``no match on CPU type {string}, default used''
  981.                     operand for a -p option can't be matched.
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                                     - 16 -
  995.  
  996.  
  997.  
  998.                ``cannot allocate string storage''
  999.                     Request to operating system for more memory
  1000.                     failed.  Fatal error.  The string storage pool
  1001.                     is where the character representation of symbols
  1002.                     and names for include files are stored.
  1003.  
  1004.                ``cannot allocate symbol space''
  1005.                     Request to operating system for more memory
  1006.                     failed.  Fatal error.  The symbol table is full.
  1007.                     The symbol space is the set of arrays where the
  1008.                     symbol values and other numeric information is
  1009.                     stored.
  1010.  
  1011.                ``cannot redefine reserved symbol''
  1012.                     Error in defining reserved symbols. Two calls to
  1013.                     "reservedsym()" with the same character string
  1014.                     value exist in the setup. Fatal error.  Should
  1015.                     not occur in a production executable.
  1016.  
  1017.                ``excessive number of subexpressions''
  1018.                     The first pass ran out of element storage for
  1019.                     the expression parse tree.  The expression is
  1020.                     too complex.  Internal error which should never
  1021.                     occur.  Fatal error.
  1022.  
  1023.                ``unable to allocate symbol index''
  1024.                     Request to operating system for more memory
  1025.                     failed.  Fatal error.  The symbol table is full.
  1026.                     The symbol index is used in the output pass to
  1027.                     direct symbol references to the symbol table
  1028.                     entry.
  1029.  
  1030.           6.1.3  Error
  1031.  
  1032.                ``ELSE with no matching if''
  1033.                ``ENDI with no matching if''
  1034.                     mismatched if/else/endi results in an else/endi
  1035.                     left over
  1036.  
  1037.                ``IF stack overflow''
  1038.                     more than IFSTKDEPTH (32) nested if statements
  1039.  
  1040.                ``Overlength/Unterminated Line''
  1041.                     line longer than input buffer, or not terminated
  1042.                     with newline character.
  1043.  
  1044.                ``active IF at end of file''
  1045.                     mismatched if/else/endi results in an unclosed
  1046.                     if
  1047.  
  1048.                ``cannot change symbol value with EQU''
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.                                     - 17 -
  1061.  
  1062.  
  1063.  
  1064.                     symbol is already defined.
  1065.  
  1066.                ``cannot change symbol value with SET''
  1067.                     symbol is already defined, but not with a Set
  1068.                     statement.
  1069.  
  1070.                ``cannot create character translation table''
  1071.                     the internal table for a character translation
  1072.                     set cannot be allocated due to lack of space, or
  1073.                     more translation sets than the assembler is
  1074.                     configured for.
  1075.  
  1076.                ``cannot open include file''
  1077.                     The include file cannot be opened for reading,
  1078.                     or not enough system resources are available to
  1079.                     open the file.
  1080.  
  1081.                ``character already defined 'char' ''
  1082.                     the character is already present in a previous
  1083.                     CHARDEF statement for this translation set.
  1084.  
  1085.                ``expression exceeds available field width''
  1086.                     The value of an expression is too large to fit
  1087.                     into the field of the instruction.  Relative
  1088.                     branch target is too far away.
  1089.  
  1090.                ``expression fails validity test''
  1091.                     An explicit test programmed in the generation
  1092.                     string for the instruction failed.  These
  1093.                     conditions are documented in the appendix for
  1094.                     the specific instruction set.
  1095.  
  1096.                ``expression stack overflow''
  1097.                     Too many level of parenthesis or complex
  1098.                     expression with operator precedence that results
  1099.                     in the expression evaluation stack overflowing.
  1100.  
  1101.                ``include file nesting limit exceeded''
  1102.                     include files are nested to more than
  1103.                     FILESTKDPTH (20) levels deep.  "cannot open
  1104.                     include file" usually occurs first.
  1105.  
  1106.                ``invalid char in instruction generation''
  1107.                     Internal error, instruction generation string is
  1108.                     not defined properly.  Should not occur in a
  1109.                     production executable.
  1110.  
  1111.                ``invalid character constant 'char' ''
  1112.                     A character specification in a string constant
  1113.                     isn't properly formed.
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.                                     - 18 -
  1127.  
  1128.  
  1129.  
  1130.                ``invalid character to define 'char' ''
  1131.                     a constant in the string in a CHARDEF statement
  1132.                     is of a form (octal, hex, or improperly formed)
  1133.                     that does not have a translation table entry.
  1134.  
  1135.                ``invalid opcode''
  1136.                     No such string occurs in the opcode symbol
  1137.                     table.  Opcode strings are converted to
  1138.                     uppercase before comparison, and therefore are
  1139.                     case insensitive.
  1140.  
  1141.                ``invalid operands''
  1142.                ``invalid operands/illegal instruction for cpu''
  1143.                     statement has a valid opcode, with the correct
  1144.                     syntax, but no code generation can be found in
  1145.                     the table for these operands
  1146.  
  1147.                ``invalid syntax for instruction''
  1148.                     opcode is valid, but not for this syntax form
  1149.  
  1150.                ``more characters than expressions''
  1151.                ``more expressions than characters''
  1152.                     A mismatch between the string constant and the
  1153.                     number of expressions in a CHARDEF statement.
  1154.  
  1155.                ``multiple definition of label''
  1156.                     label symbol is already defined.
  1157.  
  1158.                ``no CHARSET statement active''
  1159.                     a CHARDEF statement occurs before any CHARSET
  1160.                     statement.
  1161.  
  1162.                ``noncomputable expression for EQU''
  1163.                ``noncomputable expression for ORG''
  1164.                ``noncomputable expression for SET''
  1165.                ``noncomputable result for RMB expression''
  1166.                     expression contains reference to symbols that
  1167.                     have not yet been defined, and thus has no
  1168.                     numeric value.
  1169.  
  1170.                ``nonexistent character translation table''
  1171.                     expression in a CHARUSE statement does not
  1172.                     correspond to any CHARSET statements label.
  1173.  
  1174.                ``overflow in instruction generation''
  1175.                ``overflow in polish expression conversion''
  1176.                     The intermediate file line being built exceeds
  1177.                     the length of the buffer.  The expression is too
  1178.                     complex.
  1179.  
  1180.                ``syntax error at/before character ^{character}''
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.                                     - 19 -
  1193.  
  1194.  
  1195.  
  1196.                ``syntax error at/before character {character}''
  1197.                ``syntax error at/before token {symbol/constant}''
  1198.                ``syntax error at invalid token {constant/string} ''
  1199.                ``syntax error at/before string {string} ''
  1200.                ``syntax error at/before End of Line''
  1201.                ``syntax error at/before {relational op}''
  1202.                ``syntax error at/before Undeterminable Symbol''
  1203.                ``syntax error - undetermined yyerror type''
  1204.                     statement is in a form that the first pass
  1205.                     parser cannot recognize.  The next syntactic
  1206.                     element is inappropriate for whatever language
  1207.                     element the parser is working on.
  1208.  
  1209.                ``error or premature end of intermediate file''
  1210.                ``syntax error - cannot backup''
  1211.                ``unimplemented width''
  1212.                ``unknown intermediate file command''
  1213.                ``yacc stack overflow''
  1214.                     Internal errors, should not occur.
  1215.  
  1216.                ``undefined character value 'char' ''
  1217.                     A string constant contains a character not
  1218.                     defined in a CHARDEF statement for the current
  1219.                     character translation.
  1220.  
  1221.                ``undefined symbol {symbolname}''
  1222.                     symbol has no definition anywhere in file.
  1223.  
  1224.           6.1.4  Warnings
  1225.  
  1226.                ``character translation value truncated''
  1227.                     An expression in a CHARDEF statment has a value
  1228.                     less than zero or greater then 255.
  1229.  
  1230.                ``forward reference to SET/EQU symbol''
  1231.                     A symbol in an expression is defined in a
  1232.                     set/equ statement that occurs after the line.
  1233.                     For set statements, the value of the symbol is
  1234.                     that defined in the set statement closest to the
  1235.                     end of the file.
  1236.  
  1237.                ``string constant in expression more than 2
  1238.                     characters long''
  1239.                     The first two characters are used as the numeric
  1240.                     value of the subexpression.
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.                                     - 20 -
  1259.  
  1260.  
  1261.  
  1262.           6.2  Listing
  1263.  
  1264.           When the -l option is used, the detailed listing is output
  1265.           to the given file.  This consists of the symbol listing
  1266.           followed by the annotated listing.
  1267.  
  1268.           6.2.1  Symbol_Table  The symbol listing is printed three
  1269.           symbols across, with the value then name of the symbol.
  1270.           Undefined symbols will have "????????" in their value
  1271.           field.  The symbols are listed in order of first
  1272.           occurrence in the input.  Only the first fifteen
  1273.           characters of a symbol are printed.
  1274.  
  1275.           6.2.2  Instruction_Lines  The source statements are
  1276.           printed in the same form as they were input with no
  1277.           reformatting.  Following the source line, will be any
  1278.           error or warning messages associated with the line.
  1279.           Statements which generate data will be preceded with the
  1280.           address and data for them in hexadecimal format.  If more
  1281.           than six bytes of data are generated, the remainder will
  1282.           be printed on the following lines, with up to sixteen
  1283.           bytes per line.  All data generated is printed in the
  1284.           file.  Statements that don't generate data but have some
  1285.           value oriented operation, like EQU, SET, ORG, or RESERVE,
  1286.           will print that value in the first 24 columns of the
  1287.           source line.
  1288.  
  1289.           6.3  Symbol_File
  1290.  
  1291.           When the -s option is used, the symbol table is printed to
  1292.           the given file.  The format is one symbol per line,
  1293.           address then symbol name.  If the symbol is undefined,
  1294.           "????????" is printed for the address.  The symbols are
  1295.           printed in the order of first occurrence, either
  1296.           definition or reference, in the source file.  This feature
  1297.           is provided so the system sort utility can be used to
  1298.           produce symbol tables sorted by either address or name.
  1299.           The entire symbol name is printed.
  1300.  
  1301.           6.4  Binary_Output
  1302.  
  1303.           6.4.1  Intel_Hex_Record_Format  The Intel hex record is a
  1304.           printable text string with an ASCII character representing
  1305.           4 bits of a byte.  The characters used are "0" through "9"
  1306.           and "a" through "f", representing binary data 0000 to
  1307.           01001, and 1010 through 1111.  There are always two ASCII
  1308.           characters used to represent 1 byte, the high half, then
  1309.           the low half.  There is one record per line in a text
  1310.           file. This format is accepted by most of prom programmers.
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.                                     - 21 -
  1325.  
  1326.  
  1327.  
  1328.           Record Layout
  1329.  
  1330.                :ccaaaattddddddddddkk
  1331.  
  1332.                ':'       indicator character
  1333.  
  1334.                cc        ascii-hex representation of an 8 bit count
  1335.                          of data characters
  1336.  
  1337.                aaaa      ascii-hex representation of 16 bit address
  1338.  
  1339.                tt        ascii-hex representation of an 8 bit type
  1340.  
  1341.                          00        the address is the first location
  1342.                                    to store the data
  1343.  
  1344.                          01        the address is the location to
  1345.                                    start execution, the count is 00,
  1346.                                    no data is present.
  1347.  
  1348.                dd...     ascii-hex representation of the data, two
  1349.                          characters per byte. The number of 8 bit
  1350.                          bytes is given by the count field.
  1351.  
  1352.                kk        ascii-hex representation of an 8 bit
  1353.                          checksum.  The sum of the binary
  1354.                          representation, modulo 256, of the count,
  1355.                          the high half of the address, the low half
  1356.                          of the address, the type, all the data
  1357.                          bytes, and the checksum must be zero.
  1358.  
  1359.  
  1360.           7.  Program_Limits
  1361.  
  1362.           Line Length                   256 characters including end
  1363.                                         of line control characters
  1364.  
  1365.           Number of Symbols
  1366.  
  1367.                                         - The maximum allocatable
  1368.                                           block size divided by the
  1369.                                           size of a pointer.  For a
  1370.                                           iAPX286, about 16000
  1371.                                           entries.
  1372.  
  1373.                                         - The amount of allocatable
  1374.                                           memory divided by the
  1375.                                           amount of space per
  1376.                                           symbol.  For an iAPX286,
  1377.                                           22 + 1 + the length of the
  1378.                                           string bytes.
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.                                     - 22 -
  1391.  
  1392.  
  1393.  
  1394.           Symbol Length                 See line length
  1395.  
  1396.           Output                        A 16 bit address in the
  1397.                                         output record format limits
  1398.                                         output to 65536 binary
  1399.                                         bytes.
  1400.  
  1401.           Expressions per Line          128 (in BYTE and WORD
  1402.                                         statements)
  1403.  
  1404.           Strings per Line              128 (in STRING statements)
  1405.  
  1406.           Nested If Statements          32 levels
  1407.  
  1408.           Nested Include Files          20 or whatever the operating
  1409.                                         system allows
  1410.  
  1411.           Subexpressions per Line       258 symbols, constants,
  1412.                                         operators (total)
  1413.  
  1414.           Character Translation Sets    5 sets, plus the default
  1415.                                         (host) character set
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.                                    CONTENTS
  1461.  
  1462.  
  1463.           1.  Disclaimer........................................   1
  1464.  
  1465.           2.  Introduction......................................   1
  1466.               2.1  This Manual..................................   1
  1467.               2.2  Notation.....................................   1
  1468.  
  1469.           3.  Invocation........................................   1
  1470.               3.1  Input File...................................   1
  1471.               3.2  Listing File.................................   1
  1472.               3.3  Hex Output File..............................   2
  1473.               3.4  Symbol Listing File..........................   2
  1474.               3.5  Debug........................................   2
  1475.               3.6  Processor Selection..........................   2
  1476.  
  1477.           4.  Source Input File.................................   3
  1478.               4.1  Input Lines..................................   3
  1479.               4.2  Syntactic Elements...........................   4
  1480.               4.3  Expressions..................................   6
  1481.  
  1482.           5.  Statements........................................   9
  1483.               5.1  Label Only Line..............................  10
  1484.               5.2  End..........................................  10
  1485.               5.3  File Inclusion...............................  10
  1486.               5.4  Conditional Assembly.........................  10
  1487.               5.5  Symbolic Constants...........................  11
  1488.               5.6  Location Counter Value Setting...............  12
  1489.               5.7  Data Definitions.............................  12
  1490.               5.8  Defining Target Character Sets...............  13
  1491.               5.9  Machine Instructions.........................  14
  1492.  
  1493.           6.  Output............................................  15
  1494.               6.1  Program Generated Messages and Errors........  15
  1495.               6.2  Listing......................................  20
  1496.               6.3  Symbol File..................................  20
  1497.               6.4  Binary Output................................  20
  1498.  
  1499.           7.  Program Limits....................................  21
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.                                     - i -
  1515.  
  1516.  
  1517.  
  1518.  
  1519.